pontarius-xmpp-0.0.5.0: Documentation/Pontarius XMPP Manual.lyx

#LyX 2.0 created this file. For more info see http://www.lyx.org/
\lyxformat 413
\begin_document
\begin_header
\textclass article
\use_default_options true
\maintain_unincluded_children false
\language english
\language_package default
\inputencoding auto
\fontencoding global
\font_roman default
\font_sans default
\font_typewriter default
\font_default_family default
\use_non_tex_fonts false
\font_sc false
\font_osf false
\font_sf_scale 100
\font_tt_scale 100

\graphics default
\default_output_format default
\output_sync 0
\bibtex_command default
\index_command default
\paperfontsize default
\spacing single
\use_hyperref false
\papersize default
\use_geometry false
\use_amsmath 1
\use_esint 1
\use_mhchem 1
\use_mathdots 1
\cite_engine basic
\use_bibtopic false
\use_indices false
\paperorientation portrait
\suppress_date false
\use_refstyle 1
\index Index
\shortcut idx
\color #008000
\end_index
\secnumdepth 3
\tocdepth 3
\paragraph_separation indent
\paragraph_indentation default
\quotes_language english
\papercolumns 1
\papersides 1
\paperpagestyle default
\tracking_changes false
\output_changes false
\html_math_output 0
\html_css_as_file 0
\html_be_strict false
\end_header

\begin_body

\begin_layout Title
Pontarius XMPP 0.1 Manual (Second Draft)
\end_layout

\begin_layout Author
The Pontarius Project
\end_layout

\begin_layout Date
The 15th of June, 2011
\end_layout

\begin_layout Standard
\begin_inset CommandInset toc
LatexCommand tableofcontents

\end_inset


\end_layout

\begin_layout Section
Introduction
\end_layout

\begin_layout Standard
Pontarius XMPP aims to be a convenient-to-use, powerful, correct, secure,
 and extendable XMPP client library for Haskell.
 It is written by Jon Kristensen and Mahdi Abdinejadi.
 Being licensed under the GNU Lesser General Public License, Pontarius XMPP
 is free and open source software.
\end_layout

\begin_layout Section
Features and Implementation Specifics
\end_layout

\begin_layout Standard
Pontarius XMPP 0.1 implements the client capabilities of the XMPP Core specificat
ion (RFC 6120)
\begin_inset Foot
status open

\begin_layout Plain Layout
http://tools.ietf.org/html/rfc6120
\end_layout

\end_inset

.
 Below are the specifics of our implementation.
\end_layout

\begin_layout Itemize
The client is always the initiating entity
\end_layout

\begin_layout Itemize
A client-of-server connection is always exactly one TCP connection
\end_layout

\begin_layout Itemize
TLS is supported for client-to-server confidentiality
\end_layout

\begin_layout Itemize
Only the SCRAM authentication method is supported
\end_layout

\begin_layout Itemize
...
\end_layout

\begin_layout Standard
Later versions will add supports for different XMPP extensions, such as
 RFC 6121 (XMPP IM), XEP-0004: Data Forms, and XEP-0077: In-Band Registration.
\begin_inset Foot
status open

\begin_layout Plain Layout
XMPP RFCs can be found at http://xmpp.org/xmpp-protocols/rfcs/, and the so-called
 XEPs at http://xmpp.org/xmpp-protocols/xmpp-extensions/.
\end_layout

\end_inset


\end_layout

\begin_layout Section
Usage
\end_layout

\begin_layout Standard
Working with Pontarius XMPP is mostly done asynchronously; Pontarius XMPP
 ``owns'' the XMPP thread, and calls different StateT s m a callback functions
 in the client.
 StateT is a monad transformer which allows the functions to be stateful
 (being able to access and modify the arbitrary client-defined state of
 type s) and to be executed on top of a MonadIO m monad (typically IO).
\end_layout

\begin_layout Subsection
Creating the session
\end_layout

\begin_layout Standard
Setting up an XMPP session is done through the (blocking) session function:
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

session :: (MonadIO m, ClientState s m) => s ->
\end_layout

\begin_layout Plain Layout

	[ClientHandler s m] -> (StateT s m ()) -> m ()
\end_layout

\end_inset


\end_layout

\begin_layout Standard
The first parameter (of type s) is an arbitrary state that is defined by
 the client.
 This is the initial state, and it will be passed to the stateful client
 callbacks.
 It will typically be modified by the client.
\end_layout

\begin_layout Standard
The second parameter is the list of client handlers to deal with XMPP callbacks.
 The reason why we have a list is because we want to provide a ``layered''
 system of XMPP event handlers.
 For example, XMPP client developers may want to have a dedicated handler
 to manage messages, implement a spam protection system, and so on.
 Messages are piped through these handlers one by one, and any handler may
 block the message from being sent to the next handler(s) above in the stack.
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

data MonadIO m => ClientHandler s m = ClientHandler {
\end_layout

\begin_layout Plain Layout

	messageReceived :: Maybe (Message ->
\end_layout

\begin_layout Plain Layout

	StateT s m Bool), presenceReceived :: Maybe
\end_layout

\begin_layout Plain Layout

	(Presence -> StateT s m Bool), iqReceived ::
\end_layout

\begin_layout Plain Layout

	Maybe (IQ -> StateT s m Bool),
\end_layout

\begin_layout Plain Layout

	sessionTerminated :: Maybe (TerminationReason ->
\end_layout

\begin_layout Plain Layout

	StateT s m ()) }
\end_layout

\end_inset


\end_layout

\begin_layout Standard
ClientHandler is a record which specifies four callback functions.
 The first three deals with the three XMPP stanzas, and are called once
 an XMPP stanza is received.
 These functions take the stanza in question, and are stateful with the
 current client state.
 The boolean value returned signals whether or not the message should be
 blocked to clients further down the stack.
 For example, a XEP-0030: Service Discovery handler may choose to hide disco#inf
o requests handlers above it in the stack.
 The last function is the callback that is used when the XMPP session is
 terminated.
 All callbacks are optional.
\end_layout

\begin_layout Standard
The third argument to session is a callback function that will be called
 when the session has been initialized.
\end_layout

\begin_layout Standard
Any function with access to the Session object can operate with the XMPP
 session, such as connecting the XMPP client or sending stanzas.
 More on this below.
\end_layout

\begin_layout Subsection
Connecting the client
\end_layout

\begin_layout Standard
Different clients connect to XMPP in different ways.
 Some secure the stream with TLS, and some authenticate with the server.
 Pontarius XMPP provides a flexible function to help out with this in a
 convenient way:
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

connect :: MonadIO m => Session s m -> HostName ->
\end_layout

\begin_layout Plain Layout

	PortNumber -> Maybe (Certificate, (Certificate ->
\end_layout

\begin_layout Plain Layout

	Bool)) -> Maybe (UserName, Password, Maybe
\end_layout

\begin_layout Plain Layout

	Resource) -> (ConnectResult -> StateT s m ()) ->
\end_layout

\begin_layout Plain Layout

	StateT s m ()
\end_layout

\end_inset


\end_layout

\begin_layout Standard
This function simply takes the host name and port number to connect to,
 an optional tuple of the certificate to use and a function evaluating certifica
tes for TLS (if Nothing is provided, the connection will not be TLS secured),
 and another optional tuple with user name, password, and an optional resource
 for authentication (analogously, providing Nothing here causes Pontarius
 XMPP not to authenticate).
 The final paramter is a callback function providing the result of the connect
 action.
\end_layout

\begin_layout Standard
For more fine-grained control of the connection, use the openStream, secureWithT
LS, and authenticate functions.
\end_layout

\begin_layout Subsection
Sending stanzas
\end_layout

\begin_layout Standard
Sending messages and presence is trivial:
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

sendMessage :: MonadIO m => Session s m -> Message ->
\end_layout

\begin_layout Plain Layout

	StateT s m ()
\end_layout

\begin_layout Plain Layout

sendPresence :: MonadIO m => Session s m -> Presence ->
\end_layout

\begin_layout Plain Layout

	StateT s m ()
\end_layout

\end_inset


\end_layout

\begin_layout Standard
However, as Info/Query (IQ) get and set stanzas typically have a corresponding
 IQ result stanza, we offer a way to define the callback to be used for
 the IQ result immediately in the sendIQ function:
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

sendIQ :: MonadIO m => Session s m -> IQ -> Maybe (IQ ->
\end_layout

\begin_layout Plain Layout

	StateT s m Bool) -> StateT s m ()
\end_layout

\end_inset


\end_layout

\begin_layout Standard
The optional callback function is executed first with the resulting IQ,
 and its boolean return value signals whether or not the IQ result stanza
 should be blocked from being sent through the stack of client handlers.
\end_layout

\begin_layout Subsection
Example echo server
\end_layout

\begin_layout Standard
We provide an example to further illustrate the Pontarius XMPP API and to
 make it easier for developers to get started with the library.
 The program illustrates how to connect, authenticate, set a presence, and
 echo all messages received.
 It only uses one client handler.
 The contents of this example may be used freely, as if it is in the public
 domain.
 You find it in the Examples directory of the Pontarius XMPP source code.
\end_layout

\end_body
\end_document